home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Monster Media 1994 #2
/
Monster Media No. 2 (Monster Media)(1994).ISO
/
prog_pas
/
snpw32.zip
/
SNAP_P.DOC
< prev
next >
Wrap
Text File
|
1994-05-20
|
35KB
|
925 lines
SNAP_P
The Pascal Source Reformatter
for
DOS and Windows
COPYRIGHT⌐ 1992, 1993, 1994 JAMES L. ALLISON ALL RIGHTS RESERVED
James L. Allison
Neptune Systems
1703 Neptune Lane
Houston, TX 77062
Voice 713-488-5722
FAX 713-486-0375
INTERNET: 71565.303@compuserve.com
Why Use SNAP_P
Rapid evaluation, cost savings and debugging ease are the main
reasons for using a standard printer. If you are working with a
group of programmers, a standard source code format makes
reading, managing, integrating and maintaining your product far
less expensive and more reliable. Everyone can read everyone
else's code. Turnover becomes less of a headache. If you import
code from outside ( another department, a technical journal or a
BBS ) the ability to snap that code into your own format is
critical for evaluation. If you are working alone a standard
printer gets all of your source into a format that you will be
able to read months after you forgot why you wrote it in the
first place. If you are in school a standard printer will give
your reports the professional look that instructors respect.
The biggest advantage is that structural errors in a program
appear instantly in a listing that has uniform indentation and
capitalization. It is far easier to write error-free code when
you can see what you are doing. The best debugger is a standard
printer.
About SNAP_P
For safety, SNAP_P will not change the original source file
unless told to. Even then, a backup copy will be made first.
The newly structured source text will be placed in a file with
the same name as the original and the default extension ".SNP".
The Resulting formatted code is shown beside the original on your
screen for easy comparison. If you like the results and you have
not told SNAP_P to change the source, you can replace the
original ".PAS" file with the new file yourself.
SNAP_P reformats a Pascal program by adjusting margins and
internal spacing, and using standard capitalization for all
keywords and identifiers. You may specify capitalization by
either rules or by table lookup. If you choose "rules" (rather
than "table") the standard capitalization is used. You can
specify which standards and use different rules for keywords and
identifiers. If you choose table lookup an optional dictionary
of standard capitalization is maintained by SNAP_P. String
literals and comments are never changed. You can protect blocks
from any adjustment by using the echo mode described later.
Installation
This is a manual installation procedure. There is a growing
dislike of automatic procedures that do strange, unknown things
to the system. (Too many times have I had to use a full backup
tape to get rid of a program I decided not to keep. I hope you
feel the same way.)
The distribution disk contains two versions of SNAP_P: SNAP_PD
for DOS and SNAP_PW for Windows. You may use either (or both)
Page - 2
of these of these. The operation of the two versions is
virtually identical. This manual discusses the Windows version,
with notes where the DOS version differs.
SNAP_P will write several files during normal operation. The
capitalization dictionary (SNAP_P.CAP) and the optional settings
(SNAP_P.INI) will be written to the same directory where the .EXE
file is placed. In batch mode SNAP_P will create a scratch file
and a log file in this directory. It will also place a file
containing the registration form in this directory if requested.
Reformatted files (.SNP) and backup files are written to the
directory where the original source was found. If you use both
the DOS and Windows versions, they should be placed in the same
directory so the dictionary and preference files will be shared.
You should create a directory (SNAP_P, or whatever you like) on
your disk to hold these files.
Copy the SNAP_Px.EXE files to the same directory on your hard
disk. If you want to execute from anywhere in the system you
need to make sure it is in the PATH.
For DOS:
If you want to use SNAP_P as a tool in a Borland« product, do
the following:
1 Start the Borland product
2 Under the Options|Tools menu select New
3 On the resulting form enter:
Title : ~S~NAP_P
Program Path : Enter the full path name of SNAP_P.EXE
Command Line : $EDNAME $SAVE ALL
Hot Keys : Pick an available Hot Key (optional).
4 Click OK
For Windows:
Use Windows Setup|Options|Set Up Applications to create an item
in a convenient group. The group containing the compiler and
workbench is a natural place.
Removal
If you decide that you don't want to keep SNAP_P on your system,
delete SNAP_P*.* from the directory where you placed SNAP_Px.EXE.
If you created a special directory for SNAP_P, just delete the
whole thing. If you have changed your PATH or modified any tools
menus or program groups these will also need to be returned to
their original state.
Using SNAP_P
The command line syntax is: SNAP_Px [[path]filename.ext [ /brs]]
Example: SNAP_PD myprog.pas
Example: SNAP_PD myprog.pas /bs
Example: SNAP_PW
Page - 3
If the filename is given, SNAP_P opens a window containing that
file at startup, unless the /b switch is specified. The /b
switch indicates batch mode. There must be a space between the
filename and the /b switch. These switches are not case
sensitive.
The other switches allowed in batch mode are:
s Silent: do not show progress during run
r Replace existing backup file. If this is not present, a
backup copy will not be made if it would overwrite an existing
backup. This is for safety. The first time SNAP_P is used on a
source file, a backup copy is made. As you experiment with the
options, you want to keep the original intact.
In batch mode all options are those that have been specified,
except that prompting for new words is suppressed. The original
source is saved as described below and a FILENAME.SNP file is not
created. All messages are placed in SNAP_P.LOG in the SNAP_P
directory.
The DOS version of SNAP_P is a Turbo Vision(R) application, so
if you are familiar with the Borland interface you should have no
problems. If you use a mouse the interface is standard with
pull-down menus, check boxes, radio buttons and text entry
boxes. If you prefer a keyboard, press F10 to highlight the menu
bar and use the arrow and tab keys to move around. Use the space
bar to toggle check boxes. You may also use Alt-?, where ? is
the highlighted letter on the menu bar. The status bar at the
bottom of the screen gives some helpful keystrokes to get you
started. (DOS - The number in the lower right corner of the
screen is the available memory. Keep an eye on this, especially
when working with large files.)
Install SNAP_P and start it as described above.
Open a file using the Open option on the File pull-down menu.
Set capitalization rules. The rules stay in effect for each file
you reformat until explicitly changed.
Set options to use. The options stay in effect for each file you
reformat until explicitly changed.
Re-format the code.
You may repeat these steps as needed to achieve the desired
results.
You should work in the interactive mode until you get a feel for
what all of the options do, and have established a set that you
like.
Page - 4
Explanation of Menu Options
The menu bar has five pull-down items.
File:
Open: Open a file (directory menu provided)
Exit: Exit SNAP_P
Window:
Tile: Tile open windows
Cascade: Cascade open windows
Control:
General: Margins, indentation, etc.
Spaces: Space before and after punctuation
"if" Statements: if-then-else structure
Block Structure: begin-end, case, loop structures
Capitalization Rules: Capitalization rules, dictionary use
Save Style Save all options to a file. The file
will be in the home directory with the
extension .STY.
Load Style Load all options from a file
Reset to Defaults: Reset all options to default values
SNAP:
Reformat Source: Re-format source in active window
Replace Original File: Backup original file, replace with new
text
Page - 5
About:
Product Support: Where to get support
Ombudsman: ASP contact for help
Copyright: Copyright notice
Registration: Create a registration form
General Dialog Box
Scratch File Extension: SNAP_P will place the reformatted text
in a file with the same name as the source, and the given
extension. The file will be in the same directory as the
original. The purpose of this file is to give you a chance to
look at the result and compile it to make sure everything is OK.
Backup Extension Char: If you replace the original file, SNAP_P
will make a backup copy of the original in a file with the same
name as the source. The extension will be formed by replacing
the first character of the source extension with the given
character. For example, PROG.PAS will be saved as PROG.~AS. The
backup file will be placed in the same directory as the original.
If a backup already exists, it will not be replaced unless you
say so.
Indent Spaces: indent this many spaces when indent is specified
Line Wrap Indent: indent this many more spaces for continuation
lines
Minimum Line Length: stop indenting when lines get this short
Wrap to Punctuation: if multiple lines are needed, attempt to
start the continuation lines after the first one of " =" ":"
":=" "(" on the first line. If this is not possible, use the
setting in Line Wrap Indent.
Blank Line After Wrap: if continuation lines are needed insert a
blank line after the last one
Left Margin: insert this many spaces before each line
Right Margin: last character position used. Note: If a comment
or literal (or anything else) will not fit between the left and
right margins the line will be written, ignoring the margin
settings.
Break Line: insert a highly visible comment line at certain
places in the output. The line runs from the left to the right
margin. Break lines are placed in the following locations: (1)
before "implementation", (2) before top level subprograms, (3)
before unit initialization "begin" statements, (4) before main
program "begin" statements. Break lines are not placed before
subprograms nested inside other subprograms. This can help
considerably when reading someone else's code.
Filler: fill character used to form a break line. Note: Break
lines are deleted during the parse and inserted during the write.
A break line is recognized by starting with "(*" and ending with
"*)" with nothing but fill characters in between. If you want to
change the fill character for a file that already contains break
lines, you must first reformat with break lines turned off to
remove the old lines, change the fill character, turn break lines
back on, and finally reformat again. If there aren't many of
them you can delete them by hand.
Page - 6
Pad "function", etc.: add blank characters on the right to make
"function", "procedure", "constructor" and "destructor" all the
same length. This is only in effect during an object type
definition or the interface part of a unit. This can provide a
neater appearance in object type definitions.
Keep Blank Lines: retain blank lines from the original. If this
is in effect all of the options to insert blank lines will be
ignored.
UpCase GOTO, EXIT, etc.: shift all "jumps" to upper case. These
are GOTO, EXIT, HALT, BREAK and CONTINUE. If this box is
checked, it overrides all other case settings for these words.
Blank line before "with": insert a blank line before a "with"
statement
Do not reformat interface part of a unit.: Very often the
interface to a unit has been carefully hand crafted for
readability. It is usually the only part of a unit the end user
ever sees. Check this box if you want to leave the interface
alone.
Spaces Dialog Box
These control spacing within a line. Pick the options that you
prefer.
'if' Statements Dialog Box
There are many differences of opinion about how an "if" statement
should be written. The defaults are for a full "comb" structure.
This provides very readable text, and the program structure is
obvious at a glance, but many feel that it takes up too much
space on the page. Another common pattern is produced by turning
off all options except for Newline Before "else".
Take for example the following:
function isAlpha(C: char): boolean;
begin
if C in ['A' .. 'Z', 'a' .. 'z']
then
isAlpha := true
else
isAlpha := false;
end;
or,
if Cp > Length(Line)
then
begin
Block^.Append(Buf);
Buf := '';
Next_Line;
end
else
Page - 7
begin
Buf := Buf + Line[Cp];
BumpCp;
end;
These code fragments show what the default settings will produce.
The "then" and "else" parts remain indented and aligned, no
matter how complex the structure.
When you are experimenting with these you may get some unexpected
results. In particular if you turn off the Newline after "then"
or "else", you probably want to turn off the corresponding
indent.
The Blank Line After option inserts a blank line after the entire
"if-then-else" structure. If Keep Blank Lines is checked in the
General menu, the Blank Line Before/After is ignored.
Block Structure Dialog Box
This menu controls the layout of blocks. Check the boxes that
give you the appearance you like.
Indent: indent the text inside the block
Blank Line Before: insert a blank line before the beginning of
the block
Blank Line After: insert a blank line after the block. Note:
the blank line is after the block, not after the statement. For
example, in a "case" statement the blank line is after the
corresponding "end", not after the "case". For a "repeat"
statement, the blank line is after the "until" line.
If Keep Blank Lines is checked in the General menu, the Blank
Line Before/After is ignored. The Blank Line Before/After option
will never produce two blank lines together. For example, if you
check both Before and After for case statements, and your program
has two case statements together, there will be only one blank
line between them.
Indenting subprograms is very useful, especially if the file
contains nested (local) functions or procedures. Code
readability is vastly improved in these cases.
Declarations are not blocks in the "block structured" sense of
the word. These are best explained by example.
type
Switch = string[MaxSwitchLength];
Operation = (CommandLine, Interactive);
const
OPMode: Operation = Interactive;
Page - 8
var
InLines: PLineCollection;
OutFile: text;
LineNo: integer;
This segment of code was produced using the default settings for
declarations. That is, they have Blank Line Before, Blank Line
After, and Indent turned on.
Capitalization Rules Dialog Box
Upper: All upper case (example: MY_VARIABLE).
Lower: All lower case (example: my_variable).
Cap: First letter and any letter immediately following an
underscore are upper case, others in lower case (example:
My_Variable).
As is: Do not change.
Echo first: Capitalization is copied from the first occurrence
of a name. This name is not added to the dictionary.
Use Dictionary: Use the dictionary for capitalization. This is
how you control names such as "mfOKButton" etc.
Prompt for new words: If you are using the dictionary and SNAP_P
encounters an identifier not in the dictionary, you will be
prompted for the capitalization and the word will be added to the
dictionary. If this box is not checked the rules for identifiers
will be used for new words, and the new words will not be added
to the dictionary. This is always turned off during batch
operation.
Reserve Directives: Directives (virtual, forward, etc.) are not
reserved words, but many programmers treat them as such. Borland
strongly recommends that directives never be used as identifiers.
I agree. Check the box if you want to treat directives as
reserved words. If you do not check the box they will be treated
as identifiers.
About Comments
Comments are always difficult in a pretty printer; they follow no
rules. SNAP_P handles comments in the following way. If a
comment is the first non-blank on a line, it will start a new
line in the output. If it is the last non-blank on a line, it
will end a line in the output. A single line comment will remain
a single line comment. An embedded comment may or may not get
wrapped to a new line, depending on spacing, indents, etc.
Multiple line comments have the first and last lines handled
according to the above rules, while intermediate lines are copied
to the output.
Page - 9
About the Dictionary
You may want to use table lookup instead of rules for
capitalization. For most applications the rules will suffice,
but there are cases where you need more control. For example,
"ReadLn", "cmCancel", "FileName" and so on follow no particular
rules, but you want a standard appearance. This is what the
dictionary is for. Each word in the source file is capitalized
according to the dictionary. When a new word is found, you will
be prompted for the capitalization if Prompt for New Words has
been checked. You cannot change the spelling, only the looks of
the word. If you enter just a return (enter), the name will be
used as is. The dictionary is kept as a text file named
SNAP_P.CAP in the directory where you placed the .exe files, so
you can edit it whenever you like.
The words must be kept in alphabetical order. The order in the
dictionary is not case sensitive. If you need to change the
looks of a word in the dictionary use any editor to do so, but do
not change its location. Do not use a word processor that might
introduce extra characters into the file. Use a simple text
editor instead. The one you use for source code is OK.
Protecting Blocks
There are times when you want to protect a block of code from any
reorganization. This is especially true for tabular layout.
Echo mode turns SNAP_P off entirely. A {+e} inserted as a
comment in the source code starts echo mode. From that point on
the text is simply copied to the output. It is not even scanned,
except to look for a line containing only {-e}, which turns echo
mode off. Since echo mode turns off all parsing, echo mode must
respect the Pascal block and parenthesis structure. If, for
example echo mode includes a "begin" but not the matching "end"
the indent structure will be incorrect. The {+e} and {-e}
comments must appear by themselves on a line. They are not case
sensitive.
You can protect the interface to a unit by checking the "Do not
reformat interface part of a unit" box in the General dialog
under the Control menu. If this is checked the right margin
setting will be ignored.
Both left and right margins are ignored in echo mode.
Restrictions
SNAP_P assumes the original file will compile.
Tab characters, except in literals, comments and protected blocks
are deleted.
Page - 10
Null characters are replaced by blanks except in protected
blocks.
SNAP_P does not recognize conditional compilation. If anything
in a conditional compilation would "break" the block structure,
echo mode should be used.
Control characters in strings may be written using # or ^
notation. SNAP_P recognizes all of the # notation characters,
but only ['@'..'_', 'a'..z'] (in hex, this is [$40..$5F,
$61..$7A]) in ^ notation.
Items such as string literals that will not fit between margins
will be placed on a line by themselves. Indent and the right
margin will be ignored for that line.
There is an internal limit of 2048 characters in the output
buffer. If a statement exceeds this length the line will be
written at that point and the buffering will start over. The
result will be correct, and will compile correctly, but the looks
may not be what you would like; the line wrap will look awkward.
You may want to echo such statements.
You may want to echo "inline" and "asm" blocks.
Page - 11
Definition of Shareware
Shareware distribution gives users a chance to try software
before buying it. If you try a Shareware program and continue
using it, you are expected to register.
Copyright laws apply to both Shareware and commercial software,
and the copyright holder retains all rights, with a few specific
exceptions as stated below. Shareware authors are accomplished
programmers, just like commercial authors, and the programs are
of comparable quality. (In both cases, there are good programs
and bad ones!) The main difference is in the method of
distribution. The author specifically grants the right to copy
and distribute the software, either to all and sundry or to a
specific group. For example, some authors require written
permission before a commercial disk vendor may copy their
Shareware.
Shareware is a distribution method, not a type of software. You
should find software that suits your needs and pocketbook,
whether it's commercial or Shareware. The Shareware system makes
fitting your needs easier, because you can try before you buy.
And because the overhead is low, prices are low also. Shareware
has the ultimate money-back guarantee -- if you don't use the
product, you don't pay for it.
Disclaimer - Agreement
Users of SNAP_P must accept this disclaimer of warranty: "SNAP_P
is supplied as is. The author disclaims all warranties,
expressed or implied, including, without limitation, the
warranties of merchantability and of fitness for any purpose. The
author assumes no liability for damages, direct or consequential,
which may result from the use of SNAP_P."
SNAP_P is a "shareware program" and is provided at no charge to
the user for evaluation. Feel free to share it with your
friends, but please do not give it away altered or as part of
another system. The essence of "user-supported" software is to
provide personal computer users with quality software without
high prices, and yet to provide incentive for programmers to
continue to develop new products. If you find this program
useful and find that you are using SNAP_P and continue to use
SNAP_P after a reasonable trial period, you must make a
registration payment of $35.00 to Neptune Systems.
The $35.00 registration fee will license one copy of each of the
DOS and Windows version for use on any one computer at any one
time. You must treat this software just like a book. A book
cannot be read by two different persons at the same time. This
software may be used by any number of people and may be freely
moved from one computer location to another, so long as there is
no possibility of it being used at one location while it's being
used at another.
Page - 12
Commercial users of SNAP_P must register and pay for their copies
of SNAP_P within 30 days of first use or their license is
withdrawn. Site-License arrangements may be made by contacting
Neptune Systems.
Anyone distributing SNAP_P for any kind of remuneration must
first contact Neptune Systems at the address above for
authorization. This authorization will be automatically granted
to distributors recognized by the (ASP) as adhering to its
guidelines for shareware distributors, and such distributors may
begin offering SNAP_P immediately (However Neptune Systems must
still be advised so that the distributor can be kept up-to-date
with the latest version of SNAP_P.)
You are encouraged to pass a copy of SNAP_P along to your friends
for evaluation. Please encourage them to register their copy if
they find that they can use it. All registered users will
receive a copy of the latest version of the SNAP_P system without
the registration reminder at the beginning and end, and a laser
printed copy of this manual with screen capture illustrations.
They will also receive free technical support via U.S. mail,
CompuServe electronic mail or telephone for a period of six
months after registration.
Ombudsman
This program is produced by a member of the Association of
Shareware Professionals (ASP). ASP wants to make sure that the
shareware principle works for you. If you are unable to resolve a
shareware-related problem with an ASP member by contacting the
member directly, ASP may be able to help. The ASP Ombudsman can
help you resolve a dispute or problem with an ASP member, but
does not provide technical support for members' products. Please
write to the ASP Ombudsman at 545 Grover Road, Muskegon, MI
49442-9427 USA, FAX 616-788-2765 or send a CompuServe message via
CompuServe Mail to ASP Ombudsman 70007,3536.
Page - 13
Copyright ⌐ 1994 by Neptune Systems. All rights reserved. All
Borland products mentioned are trademarks or registered
trademarks of Borland International, Inc. Windows as used in
this manual refers to the windows system from Microsoft
Corporation.
Windows, as used in this manual, is a trademark of Microsoft
Corporation.
Borland International, Inc.
Setting options is explained later in this manual.
Turbo Vision is a trademark of Borland International, Inc.
The illustrations in this manual are from the Windows version.
The DOS versions are functionally the same.
The DOS version also has a status bar at the bottom of the
screen. This defines single keystrokes for Exit, Close, Toggle
43/50 line mode and Menu.
Page - 14
